chore(design-system): harness context docs. SCORE-1998 by brbrown25 · Pull Request #1369 · securityscorecard/design-system

brbrown25 · 2026-06-17T20:21:57Z

What

Adds agent-readable harness context files (generated by /index-project):

AGENTS.md — SSC Claude Code Harness agent roster + invocation guide
docs/ai/architecture.md — this service's architecture (from the harness encyclopedia)
docs/ai/conventions.md — coding tenets, PR rules, submodule rules

Why

Gives any engineer or coding agent working in design-system a current description of the agent roster and this service's architecture/conventions.

Approach

Pure documentation. No code touched. Part of a PV1-wide rollout tracked by SCORE-1998.

🤖 Generated with Claude Code

SCORE-1998 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

gitar-bot · 2026-06-17T20:24:11Z

+- PRs target the `alpha` branch (not `main`); `main` is only for hotfixes when `alpha`/`next`
+  don't exist. Per-PR snapshot builds are installable via
+  `yarn add @securityscorecard/design-system@pr-<PR-number>` and auto-unpublished on PR close.


⚠️ Quality: architecture.md misstates release branches (alpha/next vs main/beta)

docs/ai/architecture.md (Gotchas, lines 105-107) tells engineers and coding agents: "PRs target the alpha branch (not main); main is only for hotfixes when alpha/next don't exist." This is factually incorrect for this repo. The actual semantic-release config in .releaserc.json:2-5 defines exactly two release branches: main and beta (prerelease, channel beta). There is no alpha or next branch. This very PR also targets main, contradicting the doc.

Because these files are explicitly "agent-readable" context that drives automated planning/implementation decisions, an incorrect base-branch instruction is high-impact: an agent could open PRs against a non-existent alpha branch or wrongly treat main as hotfix-only. Update the Gotcha to reflect the real branching model (release from main; prereleases from beta).

Correct the documented branching model to match .releaserc.json (main + beta).:

- PRs target the `alpha` branch (not `main`); `main` is only for hotfixes when `alpha`/`next` don't exist. Per-PR snapshot builds are installable via + PRs target `main`, which is the primary release branch; `beta` is a prerelease channel (see `.releaserc.json`). Per-PR snapshot builds are installable via `yarn add @securityscorecard/design-system@pr-<PR-number>` and auto-unpublished on PR close.

_{Was this helpful? React with 👍 / 👎}

gitar-bot

⚠️ This PR is blocked due to unresolved code review findings.

Comment gitar unblock to override this block and allow merging.

_{Configure merge blocking · Maintainers can dismiss this review. Gitar never approves changes.}

gitar-bot · 2026-06-17T20:24:14Z

Code Review ⚠️ Changes requested 0 resolved / 1 findings

Adds documentation for the harness context and agent roster, but requires correction to the release branch terminology in architecture.md which currently misstates alpha/next workflows.

⚠️

Quality: architecture.md misstates release branches (alpha/next vs main/beta)

📄 docs/ai/architecture.md:105-107

docs/ai/architecture.md (Gotchas, lines 105-107) tells engineers and coding agents: "PRs target the alpha branch (not main); main is only for hotfixes when alpha/next don't exist." This is factually incorrect for this repo. The actual semantic-release config in .releaserc.json:2-5 defines exactly two release branches: main and beta (prerelease, channel beta). There is no alpha or next branch. This very PR also targets main, contradicting the doc.

Because these files are explicitly "agent-readable" context that drives automated planning/implementation decisions, an incorrect base-branch instruction is high-impact: an agent could open PRs against a non-existent alpha branch or wrongly treat main as hotfix-only. Update the Gotcha to reflect the real branching model (release from main; prereleases from beta).

Correct the documented branching model to match .releaserc.json (main + beta).

- PRs target the `alpha` branch (not `main`); `main` is only for hotfixes when `alpha`/`next`
  don't exist. Per-PR snapshot builds are installable via
+ PRs target `main`, which is the primary release branch; `beta` is a prerelease channel
  (see `.releaserc.json`). Per-PR snapshot builds are installable via
  `yarn add @securityscorecard/design-system@pr-<PR-number>` and auto-unpublished on PR close.

🤖 Prompt for agents

Code Review: Adds documentation for the harness context and agent roster, but requires correction to the release branch terminology in architecture.md which currently misstates alpha/next workflows.

1. ⚠️ Quality: architecture.md misstates release branches (alpha/next vs main/beta)
   Files: docs/ai/architecture.md:105-107

   `docs/ai/architecture.md` (Gotchas, lines 105-107) tells engineers and coding agents: "PRs target the `alpha` branch (not `main`); `main` is only for hotfixes when `alpha`/`next` don't exist." This is factually incorrect for this repo. The actual semantic-release config in `.releaserc.json:2-5` defines exactly two release branches: `main` and `beta` (prerelease, channel `beta`). There is no `alpha` or `next` branch. This very PR also targets `main`, contradicting the doc.
   
   Because these files are explicitly "agent-readable" context that drives automated planning/implementation decisions, an incorrect base-branch instruction is high-impact: an agent could open PRs against a non-existent `alpha` branch or wrongly treat `main` as hotfix-only. Update the Gotcha to reflect the real branching model (release from `main`; prereleases from `beta`).

   Fix (Correct the documented branching model to match .releaserc.json (main + beta).):
   - PRs target the `alpha` branch (not `main`); `main` is only for hotfixes when `alpha`/`next`
     don't exist. Per-PR snapshot builds are installable via
   + PRs target `main`, which is the primary release branch; `beta` is a prerelease channel
     (see `.releaserc.json`). Per-PR snapshot builds are installable via
     `yarn add @securityscorecard/design-system@pr-<PR-number>` and auto-unpublished on PR close.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.
Unblock → Override a blocking verdict and allow merging.

Comment with these commands to change:

`Auto-apply`	`Compact`	`Unblock`
`gitar auto-apply:on`	`gitar display:verbose`	`gitar unblock`

_{Was this helpful? React with 👍 / 👎 | Gitar}

github-actions · 2026-06-17T20:26:49Z

🚀 Snapshot Build Published

A snapshot version has been published to GitHub Packages for testing:

Snapshot Version: 2.42.0-snapshot-cfb40ba7
Current Version: 2.42.0 (from registry/git tags)
Tag: pr-1369

You can install this version in your project using (with .npmrc configured for @securityscorecard:registry=https://npm.pkg.github.com and auth):

yarn add @securityscorecard/design-system@pr-1369

Published to GitHub Packages; snapshot versions are not unpublished when the PR is closed.

chore: add harness context docs (AGENTS.md + docs/ai)

5f3643c

SCORE-1998 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

gitar-bot Bot reviewed Jun 17, 2026

View reviewed changes

gitar-bot Bot requested changes Jun 17, 2026

View reviewed changes

brbrown25 closed this Jun 18, 2026

brbrown25 deleted the harness/context-docs branch June 18, 2026 16:00

Navigation Menu

chore(design-system): harness context docs. SCORE-1998 - #1369

chore(design-system): harness context docs. SCORE-1998#1369
brbrown25 wants to merge 1 commit into
mainfrom
harness/context-docs

brbrown25 commented Jun 17, 2026

Uh oh!

gitar-bot Bot Jun 17, 2026 •

edited

Loading

Uh oh!

gitar-bot Bot left a comment

Uh oh!

gitar-bot Bot commented Jun 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

1 participant

Conversation

brbrown25 commented Jun 17, 2026

What

Why

Approach

Uh oh!

gitar-bot Bot Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gitar-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

gitar-bot Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 17, 2026

🚀 Snapshot Build Published

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

1 participant

gitar-bot Bot Jun 17, 2026 •

edited

Loading

gitar-bot Bot commented Jun 17, 2026 •

edited

Loading